The file assets/agents-routing-snippet.md is referenced here but is not included in the pull request. This will cause a FileNotFoundError when running the installer with the --install-agents flag (which is recommended in the README). Please add the missing file to the repository.

When pushing a new branch (remote_sha is all zeros), setting range to "$local_sha" causes git log to traverse the entire commit history back to the root commit. In non-trivial repositories, this will be extremely slow and will likely trigger false positives on old commits. Additionally, git diff --name-only "$local_sha" compares the commit against the working tree rather than finding the files changed in the commits being pushed.

Instead, use git log with --not --remotes to target only the new commits being pushed.

To ensure idempotency and prevent duplicate snippet appends on subsequent installer runs, the installer should guarantee that the snippet is wrapped with the BEGIN_MARKER and END_MARKER before writing to AGENTS.md.

def install_agents_snippet(snippet_path: Path, agents_path: Path) -> str:
    snippet = snippet_path.read_text(encoding="utf-8").strip()
    if not (snippet.startswith(BEGIN_MARKER) and snippet.endswith(END_MARKER)):
        snippet = f"{BEGIN_MARKER}\n{snippet}\n{END_MARKER}"
    agents_path.parent.mkdir(parents=True, exist_ok=True)

    if agents_path.exists():
        current = agents_path.read_text(encoding="utf-8")
    else:
        current = ""

    if BEGIN_MARKER in current and END_MARKER in current:
        before = current.split(BEGIN_MARKER, 1)[0].rstrip()
        after = current.split(END_MARKER, 1)[1].lstrip()
        updated = f"{before}\n\n{snippet}\n\n{after}".strip() + "\n"
        action = "Updated"
    else:
        separator = "\n\n" if current.strip() else ""
        updated = f"{current.rstrip()}{separator}{snippet}\n"
        action = "Added"

    agents_path.write_text(updated, encoding="utf-8")
    return action

If the script is interrupted (e.g., via Ctrl+C) or fails during the git clone or python3 execution, the temporary directory created by mktemp -d will not be cleaned up. It is best practice to use a trap to ensure cleanup on exit.

If target is a broken symlink, target.exists() will return False, but the symlink entry still exists in the filesystem. This will cause target.mkdir to fail with a FileExistsError. Checking target.is_symlink() ensures broken symlinks are also cleaned up or backed up properly.

Using simple substring matching (token in haystack) can lead to false positives. For example, any description containing the word 'explanation' will match 'plan' and incorrectly categorize the capability under 'planning'. Consider using word boundaries or token-based matching to ensure accuracy.